openapi: 3.0.0
info:
  title: MindsDB API
  description: >-
    OpenAPI Specification for MindsDB's REST API. Each API Endpoint corresponds
    to a specific SQL Statement e.g POST /model => CREATE MODEL
  version: 0.0.1
  contact:
    email: admin@mindsdb.com
  license:
    name: GNU General Public License v3.0
    url: 'https://github.com/mindsdb/mindsdb/blob/staging/LICENSE'
servers:
  - url: 'http://127.0.0.1:47334/v1/api'
    description: MindsDB local deployments
components:
  schemas:
    Database:
      type: object
      properties:
        name:
          type: string
        engine:
          type: string
          description: Handler used to create this database (e.g. postgres)
        type:
          type: string
          description: Type of database (data | project | system)
    Model:
      type: object
      properties:
        name:
          type: string
        accuracy:
          type: number
          description: Accuracy of trained model between 0 and 1
        active:
          type: boolean
          description: Whether or not this model is currently the active version
        version:
          type: number
          description: Version of this model
        status:
          type: string
          description: Current status of this model (generating | creating | complete | error)
        predict:
          type: string
          description: Column name that this model predicts
        mindsdb_version:
          type: string
          description: MindsDB version associated with this model
        error:
          type: string
          description: Error encountered during training, if applicable
        fetch_data_query:
          type: string
          description: SQL query used to fetch training data for this model
        created_at:
          type: string
          description: Time model was created at in YYYY-MM-DD HH:MM:SS format (trained models only)
        training_time:
          type: string
          description: How long training this model took in HH:MM:SS format (trained models only)
        update:
          type: string
          description: Set to "available" when a new version of MindsDB is available that makes the model obsolete, or when new data is available in the data that was used to train the model (trained models only).
        
    Project:
      type: object
      properties:
        name:
          type: string

    Table:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          description: Type of table (data | view)

    View:
      type: object
      properties:
        name:
          type: string
        query:
          type: string
          description: SELECT query used to create the view
paths:
  '/api/databases':
    get:
      security:
        - ApiKeyAuth: []
      summary: Returns a list of database names.
      description: Gets all databases created by the user.
      responses:
        '200':
          description: A JSON array of database names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Database'

        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    post:
      security:
        - ApiKeyAuth: []
      summary: Creates a new database connection.
      description: Creates a new database connection. The example parameters below are for connecting to [MySQL](/data-integrations/mysql). See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                database:
                  type: object
                  properties:
                    name:
                      type: string
                    engine:
                      type: string
                    parameters:
                      type: object
                      description: Parameters used to connect to your data source. These example parameters are for connecting to [MySQL](/data-integrations/mysql). See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
                      properties:
                        user:
                          type: string
                        password:
                          type: string
                        host:
                          type: string
                        port:
                          type: string
                        database:
                          type: string
      responses:
        # OpenAPI spec defines '200' status as a successful operation, so even though the
        # response code is '201', we need to use '200' so docs are properly generated.
        '200':
          description: The created database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '409':
          description: Database already exists
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string

  '/api/databases/{databaseName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: Gets info about existing database.
      description: Gets info about an existing database.
      parameters:
        - name: databaseName
          in: path
          description: Name of existing database
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with database informations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'

        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string

    put:
      security:
        - ApiKeyAuth: []
      summary: Updates an existing database connection.
      description: Updates an existing database connection, or creates a new connection if one doesn't exist. The example parameters below are for updating a [MySQL](/data-integrations/mysql) connection. See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
      parameters:
        - name: databaseName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                database:
                  type: object
                  properties:
                    engine:
                      type: string
                    parameters:
                      type: object
                      description: Parameters used to connect to your data source. These example parameters are for connecting to [MySQL](/data-integrations/mysql). See [here](/data-integrations/all-data-integrations) for which parameters to use for your datasource.
                      properties:
                        user:
                          type: string
                        password:
                          type: string
                        host:
                          type: string
                        port:
                          type: string
                        database:
                          type: string
      responses:
        '200':
          description: Database was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    delete:
      security:
        - ApiKeyAuth: []
      summary: Deletes an existing database.
      description: Deletes an existing database connection by name.
      parameters:
        - name: databaseName
          in: path
          description: Name of existing database to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An empty response indicates success
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects':
    get:
      security:
        - ApiKeyAuth: []
      summary: Returns a list of projects.
      description: Gets all projects created by the user.
      responses:
        '200':
          description: A JSON array of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: Get a project by name.
      description: Gets a project created by the user.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The returned project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string

  '/api/projects/{projectName}/models':
    post:
      security:
        - ApiKeyAuth: []
      summary: This endpoint trains a new ML Model.
      description: Starts training a new Machine Learning model.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: The SQL CREATE MODEL statement used to train this model. See the [CREATE MODEL](https://docs.mindsdb.com/sql/create/model) statement 
      responses:
        '200':
          description: Model training started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    get:
      security:
        - ApiKeyAuth: []
      summary: Returns a list of models.
      description: Gets info about all models in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of models names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Model'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/models/{modelName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: Gets info about specific model.
      description: Gets info for a specific model in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Model information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    delete:
      security:
        - ApiKeyAuth: []
      summary: Deletes an existing model.
      description: Deletes a model in the project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Empty response if delete is successful
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project or model not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/models/{modelName}/predict':
    post:
      security:
        - ApiKeyAuth: []
      summary: This endpoint fetches predictions from the model.
      description: Uses this model to make a prediction for values of new data.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              properties:
                data:
                  type: object
                  description: The data for querying the model as key/value e.g column name/value. Example with [home rental prices](https://docs.mindsdb.com/sql/tutorials/home-rentals) - [{"sqft":823}]
      responses:
        '200':
          description: Model queried succesfully
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
                  description: Prediction object that contains data columns and the target value, confidence, lower and upper bound.
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project or model not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/models/{modelName}/describe':
    get:
      security:
        - ApiKeyAuth: []
      summary: Describe a model
      description: Gets the attributes of a specific model.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: modelName
          in: path
          description: The name of the model
          required: true
          schema:
            type: string
      requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  attribute:
                    type: string
                    description: Attribute of the model to describe. See our [DESCRIBE documentation](https://docs.mindsdb.com/sql/api/describe). E.g. info, features, model

      responses:
        '200':
          description: A JSON object with model informations
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
                  description: Array containing model information
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Model not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/views':
    post:
      security:
        - ApiKeyAuth: []
      summary: This endpoint creates a view which is a result-set of the SELECT statement.
      description: Creates a [view](https://docs.mindsdb.com/sql/create/view) from a SELECT statement.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                view:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the view
                    query:
                      type: string
                      description: The SQL query that will save the result-set in a view.
      responses:
        '200':
          description: View created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/View'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    get:
      security:
        - ApiKeyAuth: []
      summary: List all views in a project
      description: Gets all views in a project.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with view names
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/View'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/projects/{projectName}/views/{viewName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: SELECT from VIEW
      description: Gets a single view.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: viewName
          in: path
          description: The name of the view
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with VIEW data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/View'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: View or project not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    delete:
      security:
        - ApiKeyAuth: []
      summary: Deletes an existing view.
      description: Deletes an existing view in the project.
      parameters:
        - name: projectName
          in: path
          description: Project name the view is in
          required: true
          schema:
            type: string
        - name: viewName
          in: path
          description: View name to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Succesfully deleted
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: View or projectnot found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    put:
      security:
        - ApiKeyAuth: []
      summary: Updates an existing view.
      description: Updates an existing view, or creates a new view if one doesn't exist.
      parameters:
        - name: projectName
          in: path
          description: The name of the project
          required: true
          schema:
            type: string
        - name: viewName
          in: path
          description: The name of the view
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                view:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the view
                    query:
                      type: string
                      description: The SQL query that will save the result-set in a view.
      responses:
        '200':
          description: View was successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/View'
        '400':
          description: Bad request format
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/databases/{databaseName}/tables':
    post:
      security:
        - ApiKeyAuth: []
      summary: This endpoint creates a new table with the predictions result-set.
      description: Creates a new table from a select query. See [CREATE table documentation](https://docs.mindsdb.com/sql/create/table).
      parameters:
      - name: databaseName
        in: path
        description: Name of the database
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                table:
                  type: object
                  properties:
                    name:
                      type: string
                    select:
                      type: string
                      description: SELECT statement to create the table from
                    replace:
                      type: boolean
                      description: Whether or not to delete a pre-existing table before creating it
      responses:
        '200':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string

    get:
      security:
        - ApiKeyAuth: []
      summary: Returns a list of tables in a database.
      description: Gets metadata for all tables in a database.
      parameters:
        - name: databaseName
          in: path
          description: The name of the database
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of tables
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Table'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
  '/api/databases/{databaseName}/tables/{tableName}':
    get:
      security:
        - ApiKeyAuth: []
      summary: SELECT from Table
      description: Gets metadata for a table in a database.
      parameters:
        - name: databaseName
          in: path
          description: The name of the database
          required: true
          schema:
            type: string
        - name: tableName
          in: path
          description: The name of the table
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A JSON object with SELECT data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Table'
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Table or database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
    delete:
      security:
        - ApiKeyAuth: []
      summary: Deletes an existing table.
      description: Deletes a table in a database.
      parameters:
        - name: databaseName
          in: path
          description: The name of the database
          required: true
          schema:
            type: string
        - name: tableName
          in: path
          description: Table name to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '401':
          description: Invalid API key error message
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '404':
          description: Table or database not found
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                items:
                  type: string